A:

Sound cards and integrated PC motherboard chipsets offering more than the usual two stereo output channels have been widely available for some time, primarily to support DVD surround playback. Game developers have used various '3D sound' solutions ranging from Dolby Surround processing to elaborate head-related transfer function implementations to give players a sense of simulated spatial orientation and distance, but only a few recent titles such as Half-Life 2 have offered the ability to render in-game sound effects and dialogue through the 5.1-channel or similar multichannel speaker systems that more and more users own. In MSS version 7.0, we've given you the ability to add true multispeaker digital audio support in an afternoon's worth of coding.

What output formats are available?

The DOS and Macintosh platforms support conventional mono/stereo output formats only. Xbox and Xbox 360 are even simpler to understand -- it's inherently a 5.1-channel system. For more information on audio support on the Xbox, see the Overview for Microsoft Xbox section .

As usual, on platforms like Win32/Win64 and the Sony PS2/PS3, things get interesting. When you call AIL_open_digital_driver (or its quick API equivalent, AIL_quick_startup), you'll need to tell Miles what audio output format to use via the channels parameter. This is an integer parameter that was previously limited to values of either 1 or 2 for mono or stereo output. Beginning with MSS 7, you can also pass a value of the enum type MSS_MC_SPEC to functions that open a digital driver. A brief explanation of these options appears below.

• MSS_MC_USE_SYSTEM_CONFIG This option causes MSS to choose an appropriate MSS_MC_SPEC setting based on the Windows control-panel settings as reported by IDirectSound::GetSpeakerConfig. This is generally the setting you should use.

• MSS_MC_MONO Conventional monaural (single-speaker) sound. Equal to the constant 1.
• MSS_MC_STEREO Conventional stereo sound. Equal to the constant 2. Miles's 3D positional math assumes two (left and right) speakers are in front of the listener at 45-degree angles.
• MSS_MC_HEADPHONES Similar to MSS_MC_STEREO, but Miles assumes the speakers are positioned directly to either side of the listener.
• MSS_MC_DOLBY_SURROUND This option assumes the user has connected a Dolby Surround-capable receiver to their (two-channel) sound card. It is identical to the Miles Dolby Surround M3D provider from earlier versions. Because DVD soundtracks downmixed to analog Dolby Surround sound pretty awful, this is no longer a very popular option for PC sound. Dolby Surround provides three logical channels (front left, front right, and monaural rear).
• MSS_MC_SRS_CIRCLE_SURROUND SRS Circle Surround(r) is a two-channel matrix format can be thought of as an improved replacement for Dolby Surround. It is compatible with consumer receivers that support Dolby, and offers 6.1 logical channels (front left, front right, front center, subwoofer, rear left, rear right, and rear center) on native Circle Surround(r)-compatible equipment. The main drawback to Circle Surround(r) is its significantly-increased CPU overhead compared to Dolby Surround.
• MSS_MC_40_DISCRETE This option assumes that four speakers (front left, front right, rear left, and rear right) are connected in a quadraphonic discrete configuration without the center speaker or subwoofer typical of 5.1 configurations. Not an especially-common channel configuration, except for a few diehard Led Zeppelin fans who haven't upgraded for awhile.
• MSS_MC_51_DISCRETE Use this option to support the 'sweet spot' of current home audio systems, the 5.1-channel discrete configuration. Again, this is largely a DVD-driven phenomenon. There is a lot of hardware out there that can support 5.1 audio these days! This is the most common format on the PS3 as well.
• MSS_MC_40_DTS Available on Sony PS2, this option provides four-channel discrete DTS encoding through the S/PDIF port. It is more efficient in terms of memory and encoding overhead than MSS_MC_51_DTS, but lacks support for the LFE and center channels. Like MSS_MC_40_DISCRETE, it assumes that at least four speakers (front left, front right, rear left, and rear right) are available.
• MSS_MC_51_DTS Available on Sony PS2, this option provides true 5.1-channel discrete DTS encoding through the S/PDIF port. DTS is surprisingly efficient on the PS2, sounds great, and is highly recommended for apps that can afford the slight (5% or so) CPU hit.
• MSS_MC_61_DISCRETE Similar to 5.1, but with a rear center speaker.
• MSS_MC_71_DISCRETE Similar to 5.1, but with side surrounds. This is a very common format for multichannel sound hardware to support, but users don't tend to have room for this many speakers. The PS3 also supports this option, but there are few speakers setups that can handle it.
• MSS_MC_81_DISCRETE Similar to 5.1, but with both side surrounds and a center rear speaker.
• MSS_MC_DIRECTSOUND3D Uses DirectSound3D for output, bypassing the Miles internal mixer.
• MSS_MC_EAX2 Adds hardware-accelerated environmental reverb effects, occlusion, obstruction, and per-sample wet/dry mix control to DirectSound3D.
• MSS_MC_EAX3 Adds exclusion and several other properties to the EAX 2 feature set.
• MSS_MC_EAX4 Higher-quality effects and new control options (see the EAX4EXAM.CPP example application), currently available only in Creative Labs' highest-end hardware.

When using the MSS_MC_USE_SYSTEM_CONFIG flag for the channels parameter, the output configuration is determined as follows (note that not all of the speaker systems are supported on all platforms):

Operating System Reports	Equivalent MSS_MC_SPEC Value
Headphones	MSS_MC_HEADPHONES
Mono speaker	MSS_MC_MONO
Quad speakers	MSS_MC_40_DISCRETE
Stereo speakers	MSS_MC_STEREO
Surround speakers	MSS_MC_SRS_CIRCLE_SURROUND
5.1 speakers	MSS_MC_51_DISCRETE
6.1 speakers	MSS_MC_61_DISCRETE
5.1 speakers	MSS_MC_51_DISCRETE
8.1 speakers	MSS_MC_81_DISCRETE

You can query the chosen MSS_MC_SPEC value by calling AIL_speaker_configuration on the returned HDIGDRIVER. Unfortunately, the control-panel or other system setting may not reflect the user's actual hardware configuration. Worst, from the sound driver's point of view, the configuration may be determined by a separate, proprietary applet -- which may or may not keep itself synchronized with the operating system settings. Further, the limited range of operating system values don't begin to address all of the possible configurations (for example, under Windows there is no option for 6.1 speakers). Therefore, it's best not to rely solely on the OS to report a meaningful speaker-configuration value; we strongly recommend offering the user the ability to select an MSS_MC_ configuration directly as part of your application's sound-options dialog. So, default to MSS_MS_USE_SYSTEM_CONFIG, but give the user the ability to override.

Understanding the DirectSound3D alternatives on Windows

On the sound card hardware, DirectSound 3D can do many of the functions that Miles provides in its software mixer. In theory, hardware mixing saves CPU time. In reality, the advantage ranges from subtle to unmeasurable! Worse, hardware processing implies hardware resources, so this means that you are limited to the number of hardware voices offered by DirectSound 3D -- typically a very small number on the order of 8 to 16.

Also note that no environmental reverb effects are supported when MSS_MC_DIRECTSOUND3D options are selected -- only the EAX options offer reverb effects in hardware. Furthermore, the DirectSound3D multispeaker positioner will work properly only if the end user's speaker configuration is set correctly in the Windows control panel and/or their sound card vendor's proprietary control application.

The EAX options add environmental reverb effects to DirectSound 3D, with all of DirectSound3D's accompanying advantages and drawbacks. But hardware acceleration of environmental reverb effects, unlike acceleration of mixing by itself, actually can save CPU time on slower machines. Unfortunately, while EAX is widely emulated in various chipsets (as well as MSS's own software mixer), there is little consistency in reverb levels and quality even among Creative Labs' own products, much less those from other vendors. If consistent reproduction across all platforms is important to your application, don't rely on hardware EAX support -- use the software mixer-based options instead.

For all of these reasons, it's better in most cases to skip the DirectSound3D/EAX options in favor of allowing the end user to select the mono, stereo, or MSS_MC_DISCRETE configuration that matches their hardware and let Miles do the mixing and environmental effects internally. Almost all games (and even next-gen console APIs) are moving towards software based sound processing - it's more reliabile, more consistent, and easier to author for.

Channel level-control options

Regardless of whether a mono, stereo, discrete multichannel, or SRS/Dolby output format is selected, the MSS software mixer gives you a couple of different ways to determine how much sound from a given HSAMPLE reaches each speaker. Obviously, the AIL_set_sample_volume_pan or AIL_set_sample_volume_levels will have the expected effect regardless of the output format. MSS 7, however, has introduced an additional scale factor that affects per-sample volume, the channel level scalar. There's one channel-level scale factor for each combination of source channel (HSAMPLE) and logical channel in the output mix (HDIGDRIVER). MSS multiplies each playing HSAMPLE's 3D/volume/pan-derived level with the channel-level scale factor at each speaker to obtain the volume at that speaker. The maximum level of each source (HSAMPLE/HSTREAM) channel at each output speaker, prior to any volume- or pan-control attenuation, may be set directly by the application via the AIL_set_sample_channel_levels function.

Many applications will never need to use AIL_set_sample_channel_levels at all. By default, MSS tries to select a reasonable mapping between source and speaker channels for a given output mode. Rules that establish the default channel-routing behavior include:

• Mono sources played in MSS_MC_MONO output mode are sent to the only available output (speaker) channel
• Mono sources played in stereo or multichannel output modes are sent to all available speaker channels
• Stereo source channels are combined for MSS_MC_MONO output
• Stereo sources played in multichannel output modes are sent to the front-left and front-right speaker channels only
• Multichannel source channels, except LFE channels, are combined for MSS_MC_MONO output
• In stereo or multichannel output modes, channels from multichannel sources which do not have a corresponding output speaker channel are steered based on their front/back and left/right spatial assignments. For example, a left-rear source channel would appear in the front-left channel in MSS_MC_STEREO mode. Any remaining unmapped source channels, such as center channels, are steered to both left and right destination channels. LFE source channels are never mapped to any output channel except LFE (if present).
• When more than two source channels are mapped to a single speaker, an attenuation factor is applied to help avoid clipping distortion. The default level scalar assigned to each channel-speaker combination is 1.0 (full scale) if there are two or fewer source channels assigned to the speaker, or 2/n if more than two channels are assigned. This corresponds to 20*log(n/2) dB down from full scale, where n is the total number of channels assigned to the speaker.

Note that some aspects of this behavior are different in MSS versions 7.1a and earlier. In these earlier releases, stereo source channels were mapped arbitrarily to successive pairs of output channels, and multichannel HSAMPLEs/HSTREAMs were not supported at all.

Another point that must be emphasized is that the behavior described above is only the default. The AIL_set_sample_channel_levels function gives your MSS application complete control over the channel-steering matrices for all of its HSAMPLEs and HSTREAMs... even 3D-positioned ones, if desired! To understand how MSS applies various internally-generated and application-supplied scale factors to HSAMPLE and HSTREAM volume levels, see the Digital Audio Pipeline section.

3D control

It's possible for MSS to determine an HSAMPLE's channel levels automatically, by performing distance and directionality calculations based on the relative positions of the HSAMPLE and its HDIGDRIVER (also known as the listener) in 3D space. Positions in 3D space are specified in left-handed coordinates (+X = right, +Y = up, +Z = front) by means of the AIL_set_sample_3D_position and AIL_set_listener_3D_position functions.

Once an HSAMPLE has been placed under 3D control, a number of additional MSS API functions can be applied to the HSAMPLE. AIL_set_sample_3D_distances determines how distance-based attenuation is applied to the sound, while the AIL_set_sample_3D_cone and AIL_set_sample_3D_orientation functions give the sound a directional falloff characteristic. AIL_set_sample_3D_velocity applies Doppler shift to the sound. Similar functions apply to the listener object associated with the HDIGDRIVER. When the MSS software mixer is in use, none of the functions whose name contains '_3D_' affect HSAMPLES that have not been assigned a 3D position.

Only monaural samples can be meaningfully assigned a 3D position with AIL_set_sample_3D_position. Assigning a 3D position to a stereo sample will result in a forced downmix to mono when that HSAMPLE is processed by the software mixer. Assigning a 3D position to a multichannel sample yields undefined results which may vary from one MSS version to the next.

Even after you call AIL_set_sample_3D_position on an HSAMPLE, the sample's channel levels may still be controlled via AIL_set_sample_channel_levels. Any additional channel-level scale factors supplied by the application are simply multiplied with the results of the 3D-positioning algorithm.

Note that the only way to disable 3D spatialization of an HSAMPLE is to reinitialize it with a call to AIL_init_sample, AIL_set_sample_info, AIL_set_sample_file, or AIL_set_named_sample_file. You can tell if a given HSAMPLE has been placed under 3D control by examining the return value from AIL_sample_3D_position.

Along the same lines, note that discrete control of channel levels is available only with the MSS software mixer; it isn't possible with the DirectSound3D/EAX options. AIL_set_sample_channel_levels and AIL_sample_channel_levels don't work at all on these configurations... and all HSAMPLEs are 3D-positioned, even ones for which you've never called AIL_set_sample_3D_position. So you'll need to open another HDIGDRIVER for 2D-only sounds like menu cues and extradiagetic sound effects, unless every sound effect in your game is 3D-positional. The examms example program demonstrates this principle.

Addressing individual speakers

MSS's multichannel implementation is based on the master speaker/channel layout plan defined by Microsoft as part of their WDM driver model for Windows 98SE and Windows 2000/XP. In this scheme, up to eighteen channels are specifiable through the use of the MSS_SPEAKER enumeration:

MSS_SPEAKER enum	Abbreviation	Numeric value
MSS_SPEAKER_FRONT_LEFT	FL	0
MSS_SPEAKER_FRONT_RIGHT	FR	1
MSS_SPEAKER_FRONT_CENTER	FC	2
MSS_SPEAKER_LOW_FREQUENCY	LFE	3
MSS_SPEAKER_BACK_LEFT	BL	4
MSS_SPEAKER_BACK_RIGHT	BR	5
MSS_SPEAKER_FRONT_LEFT_OF_CENTER	FLoC	6
MSS_SPEAKER_FRONT_RIGHT_OF_CENTER	FRoC	7
MSS_SPEAKER_BACK_CENTER	BC	8
MSS_SPEAKER_SIDE_LEFT	SL	9
MSS_SPEAKER_SIDE_RIGHT	SR	10
MSS_SPEAKER_TOP_CENTER	TC	11
MSS_SPEAKER_TOP_FRONT_LEFT	TFL	12
MSS_SPEAKER_TOP_FRONT_CENTER	TFC	13
MSS_SPEAKER_TOP_FRONT_RIGHT	TFR	14
MSS_SPEAKER_TOP_BACK_LEFT	TBL	15
MSS_SPEAKER_TOP_BACK_CENTER	TBC	16
MSS_SPEAKER_TOP_BACK_RIGHT	TBR	17

In addition to providing destination-speaker and source-channel index values for use with AIL_set_sample_channel_levels and other functions, this table defines the order in which channels must appear in multichannel source streams. As shown in the table below, only one combination of MSS_SPEAKER output channels is valid for any given number of logical output channels. (As an example, MSS_MC_61_DISCRETE always refers to a speaker configuration consisting of the FL, FR, FC, LFE, BL, BR, and BC output channels.)

MSS_MC_SPEC enum	Physical/logical channels	Logical MSS_SPEAKER array
MSS_MC_DIRECTSOUND3D	0/0	NA
MSS_MC_EAX2	0/0	NA
MSS_MC_EAX3	0/0	NA
MSS_MC_EAX4	0/0	NA
MSS_MC_MONO	1/1	FL
MSS_MC_STEREO	2/2	FL,FR
MSS_MC_HEADPHONES	2/2	FL,FR
MSS_MC_40_DISCRETE	4/4	FL,FR,BL,BR
MSS_MC_DOLBY_SURROUND	2/3	FL,FR,BC
MSS_MC_SRS_CIRCLE_SURROUND	2/7	FL,FR,FC,LF,BL,BR,BC
MSS_MC_51_DISCRETE	6/6	FL,FR,FC,LF,BL,BR
MSS_MC_61_DISCRETE	7/7	FL,FR,FC,LF,BL,BR,BC
MSS_MC_71_DISCRETE	8/8	FL,FR,FC,LF,BL,BR,SL,SR
MSS_MC_81_DISCRETE	9/9	FL,FR,FC,LF,BL,BR,BC,SL,SR

Your application doesn't normally need to worry about specific channel-ordering issues because MSS keeps track of which MSS_SPEAKERs are valid for a given HSAMPLE and output driver. And again, this is all moot when using DirectSound3D/EAX, because you don't have any control over individual channel levels to begin with.

You can obtain the number of physical and logical channels in use by calling AIL_speaker_configuration, as well as the MSS_MC_SPEC value passed to (or chosen by) AIL_open_digital_driver. As can be seen in the table above, these will be identical for all conventional (non-matrix) discrete formats, while matrix formats such as Dolby and SRS Circle Surround(r) can map three or more logical channels onto two physical channels. DirectSound3D and EAX will report zero physical channels and zero logical channels, since Windows insulates the application from these details.

Authoring multichannel content for MSS

MSS can play two types of multichannel audio files: Ogg Vorbis files and PCM .WAV files with WAVE_FORMAT_EXTENSIBLE headers. PCM .WAV files can only be played from memory; they cannot be played with AIL_open_stream. Multichannel Ogg Vorbis files, on the other hand, are compatible with all MSS playback functions.

Multichannel PCM .WAV file headers have a 32-bit channel mask value whose bits determine which speakers are intended to render the file's source channels. The so-called dwChannelMask value can be passed to AIL_set_sample_info at sample-initialization time via the AILSOUNDINFO structure's channel_mask member, and queried at any time by AIL_sample_channel_count. It should always be 0xFFFFFFFF (~0U) for a standard mono or stereo HSAMPLE. If not all of the mask bits are set, this means that the specified HSAMPLE is a multichannel sample. In this case, the values of the first 18 bits equal 1 if the corresponding MSS_SPEAKER channel is present, or 0 if not. (The LSB, i.e., dwChannelMask & 0x01, corresponds to MSS_SPEAKER_FRONT_LEFT.) The values of subsequent mask bits (bit 18 and beyond) are undefined and should be ignored.

Small (< 2 GB total) multichannel PCM .WAV files can be created through the use of the WAVMUX.EXE utility. Using WAVMUX.EXE, it's possible to create a PCM .WAV file that contains gaps in its channel mask. For instance, the command

wavmux output.wav none none none none back_left.wav back_right.wav

creates a multichannel (WAVE_FORMAT_EXTENSIBLE) .WAV file called output.wav with only its back-left and back-right channels valid. Although this is a two-channel .WAV file, it is not a "stereo" .WAV file, but rather a multichannel .WAV with a dwChannelMask value of 0x0030. Its two channels will be identified as "BL" and "BR" in the Miles Sound Player.

Miles fully supports multichannel Ogg Vorbis files. Creating a multichannel Ogg Vorbis file can be as simple as dragging the desired multichannel .WAV file onto an OggDrop window. However, dwChannelMask information from the .WAV source is not preserved in a multichannel Ogg Vorbis file. Instead, the channel layout of an Ogg Vorbis file is inferred from its channel count, according to the following table:

# of channels in Ogg Vorbis file	Effective dwChannelMask	Equivalent MSS_SPEAKER array
1	~0U (conventional mono)	(Mono, stored as FL channel)
2	~0U (conventional stereo)	FL,FR
3	0x0103 (multichannel)	FL,FR,BC
4	0x0033 (multichannel)	FL,FR,BL,BR
5	0x0037 (multichannel)	FL,FC,FR,BL,BR
6	0x003F (multichannel)	FL,FR,FC,LF,BL,BR
>6	(1 << n)-1	First n channels in MSS_SPEAKER order

Conventional stereo samples are somewhat faster to process than 2-channel multichannel samples, so MSS assumes that all two-channel Ogg Vorbis files and all standard two-channel .WAV files are stereo samples destined for the front-left/front-right speakers. If you want to perform arbitrary channel steering on a stereo file, you'll need to encode it as a multichannel .WAV file with two valid channels.

Working with speaker positions and falloff

When MSS opens an HDIGDRIVER in configurations other than DirectSound3D/EAX, it chooses a reasonable set of default positions for the speakers in the configuration. In most cases, the speakers with directional characteristics (i.e., other than the subwoofer/LFE channel) are arrayed at roughly-equal intervals around the unit circle. Sophisticated applications may wish to allow the user to alter MSS's speaker positions to match the positions of the actual speakers that surround the listener. You can call AIL_set_speaker_configuration to submit an array of up to n speaker locations, where n is the number of logical channels in the configuration as reported by AIL_speaker_configuration. The submitted speaker locations will replace the default locations chosen at driver initialization time.

Almost all games will want to specify a falloff power greater than 1.0 to exaggerate the movement of sounds between speakers. At 1.0, MSS's 3D pan function is constant in power. A sound will not appear to grow louder or software as it moves around the listener, providing it remains equidistant. Higher falloff powers can make games sound more 'interesting' due to increased apparent movement of sound sources... but this effect comes at the expense of level accuracy, as the sound will not tend to be as loud when it's positioned between speakers. The examms example program can help you judge the effect of different falloff powers.

You can use AIL_set_speaker_configuration to change the falloff power without supplying new speaker locations. To do this, simply pass 0 for n_channels and NULL for array. MSS's default falloff power is 3.0.

How do stereo HSAMPLEs work in a multi-channel environment?

As noted above, stereo samples and streams are mapped to the FR/FL channels in an output mode with >= 2 channels, and combined for output in MSS_MC_MONO mode. In most applications that don't switch between first-person and third-person points of view, it usually doesn't make sense to enable 3D positioning on a stereo sample; the channels will be downmixed to mono at runtime, taking up extra memory space and CPU time. Stereo and multichannel samples don't work at all in DirectSound3D or EAX; you'll need to open a separate HDIGDRIVER to handle them.